home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 7 / Amiga Format AFCD07 (Dec 1996, Issue 91).iso / serious / shareware / programming / emacs-complete / fsf / emacs / info / emacs-3 (.txt) < prev    next >
GNU Info File  |  1994-10-05  |  50KB  |  894 lines
  1. This is Info file ../info/emacs, produced by Makeinfo-1.54 from the
  2. input file emacs.texi.
  3. File: emacs,  Node: Position Info,  Next: Arguments,  Prev: Continuation Lines,  Up: Basic
  4. Cursor Position Information
  5. ===========================
  6.    Here are commands to get information about the size and position of
  7. parts of the buffer, and to count lines.
  8. `M-x what-page'
  9.      Print page number of point, and line number within page.
  10. `M-x what-line'
  11.      Print line number of point in the buffer.
  12. `M-x line-number-mode'
  13.      Toggle automatic display of current line number.
  14. `M-='
  15.      Print number of lines in the current region (`count-lines-region').
  16. `C-x ='
  17.      Print character code of character after point, character position
  18.      of point, and column of point (`what-cursor-position').
  19.    There are two commands for printing the current line number.  `M-x
  20. what-line' computes the current line number and displays it in the echo
  21. area.  `M-x line-number-mode' enables display of the current line
  22. number in the mode line; once you turn this on, the number updates as
  23. you move point, so it remains valid all the time.  *Note Mode Line::.
  24.    Line numbers count from one at the beginning of the buffer.  To go to
  25. a given line by number, use `M-x goto-line'; it prompts you for the
  26. line number.
  27.    By contrast, `M-x what-page' counts pages from the beginning of the
  28. file, and counts lines within the page, printing both numbers.  *Note
  29. Pages::.
  30.    While on this subject, we might as well mention `M-='
  31. (`count-lines-region'), which prints the number of lines in the region
  32. (*note Mark::.).  *Note Pages::, for the command `C-x l' which counts
  33. the lines in the current page.
  34.    The command `C-x =' (`what-cursor-position') can be used to find out
  35. the column that the cursor is in, and other miscellaneous information
  36. about point.  It prints a line in the echo area that looks like this:
  37.      Char: x (0170)  point=65986 of 563027(12%)  x=44
  38. (In fact, this is the output produced when point is before the `x=44'
  39. in the example.)
  40.    The two values after `Char:' describe the character that follows
  41. point, first by showing it and second by giving its octal character
  42. code.
  43.    `point=' is followed by the position of point expressed as a
  44. character count.  The front of the buffer counts as position 1, one
  45. character later as 2, and so on.  The next, larger number is the total
  46. number of characters in the buffer.  Afterward in parentheses comes the
  47. position expressed as a percentage of the total size.
  48.    `x=' is followed by the horizontal position of point, in columns
  49. from the left edge of the window.
  50.    If the buffer has been narrowed, making some of the text at the
  51. beginning and the end temporarily inaccessible, `C-x =' prints
  52. additional text describing the currently accessible range.  For
  53. example, it might display this:
  54.      Char: x (0170)  point=65986 of 563025(12%) <65102 - 68533>  x=44
  55. where the two extra numbers give the smallest and largest character
  56. position that point is allowed to assume.  The characters between those
  57. two positions are the accessible ones.  *Note Narrowing::.
  58.    If point is at the end of the buffer (or the end of the accessible
  59. part), `C-x =' omits any description of the character after point.  The
  60. output looks like this:
  61.      point=563026 of 563025(100%)  x=0
  62. File: emacs,  Node: Arguments,  Prev: Position Info,  Up: Basic
  63. Numeric Arguments
  64. =================
  65.    Any Emacs command can be given a "numeric argument" (also called a
  66. "prefix argument").  Some commands interpret the argument as a
  67. repetition count.  For example, `C-f' with an argument of ten moves
  68. forward ten characters instead of one.  With these commands, no argument
  69. is equivalent to an argument of one.  Negative arguments tell most such
  70. commands to move or act in the opposite direction.
  71.    If your terminal keyboard has a META key, the easiest way to specify
  72. a numeric argument is to type digits and/or a minus sign while holding
  73. down the the META key.  For example,
  74.      M-5 C-n
  75. would move down five lines.  The characters `Meta-1', `Meta-2', and so
  76. on, as well as `Meta--', do this because they are keys bound to
  77. commands (`digit-argument' and `negative-argument') that are defined to
  78. contribute to an argument for the next command.
  79.    Another way of specifying an argument is to use the `C-u'
  80. (`universal-argument') command followed by the digits of the argument.
  81. With `C-u', you can type the argument digits without holding down
  82. modifier keys; `C-u' works on all terminals.  To type a negative
  83. argument, type a minus sign after `C-u'.  Just a minus sign without
  84. digits normally means -1.
  85.    `C-u' followed by a character which is neither a digit nor a minus
  86. sign has the special meaning of "multiply by four".  It multiplies the
  87. argument for the next command by four.  `C-u' twice multiplies it by
  88. sixteen.  Thus, `C-u C-u C-f' moves forward sixteen characters.  This
  89. is a good way to move forward "fast", since it moves about 1/5 of a line
  90. in the usual size screen.  Other useful combinations are `C-u C-n',
  91. `C-u C-u C-n' (move down a good fraction of a screen), `C-u C-u C-o'
  92. (make "a lot" of blank lines), and `C-u C-k' (kill four lines).
  93.    Some commands care only about whether there is an argument, and not
  94. about its value.  For example, the command `M-q' (`fill-paragraph') with
  95. no argument fills text; with an argument, it justifies the text as well.
  96. (*Note Filling::, for more information on `M-q'.)  Plain `C-u' is a
  97. handy way of providing an argument for such commands.
  98.    Some commands use the value of the argument as a repeat count, but do
  99. something peculiar when there is no argument.  For example, the command
  100. `C-k' (`kill-line') with argument N kills N lines, including their
  101. terminating newlines.  But `C-k' with no argument is special: it kills
  102. the text up to the next newline, or, if point is right at the end of
  103. the line, it kills the newline itself.  Thus, two `C-k' commands with
  104. no arguments can kill a nonblank line, just like `C-k' with an argument
  105. of one.  (*Note Killing::, for more information on `C-k'.)
  106.    A few commands treat a plain `C-u' differently from an ordinary
  107. argument.  A few others may treat an argument of just a minus sign
  108. differently from an argument of -1.  These unusual cases are described
  109. when they come up; they are always for reasons of convenience of use of
  110. the individual command.
  111.    You can use a numeric argument to insert multiple copies of a
  112. character.  This is straightforward unless the character is a digit; for
  113. example, `C-u 6 4 a' inserts 64 copies of the character `a'.  But this
  114. does not work for inserting digits; `C-u 6 4 1' specifies an argument
  115. of 641, rather than inserting anything.  To separate the digit to
  116. insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u
  117. 1' does insert 64 copies of the character `1'.
  118.    We use the term "prefix argument" as well as "numeric argument" to
  119. emphasize that you type the argument before the command, and to
  120. distinguish these arguments from minibuffer arguments that come after
  121. the command.
  122. File: emacs,  Node: Minibuffer,  Next: M-x,  Prev: Basic,  Up: Top
  123. The Minibuffer
  124. **************
  125.    The "minibuffer" is the facility used by Emacs commands to read
  126. arguments more complicated than a single number.  Minibuffer arguments
  127. can be file names, buffer names, Lisp function names, Emacs command
  128. names, Lisp expressions, and many other things, depending on the command
  129. reading the argument.  You can use the usual Emacs editing commands in
  130. the minibuffer to edit the argument text.
  131.    When the minibuffer is in use, it appears in the echo area, and the
  132. terminal's cursor moves there.  The beginning of the minibuffer line
  133. displays a "prompt" which says what kind of input you should supply and
  134. how it will be used.  Often this prompt is derived from the name of the
  135. command that the argument is for.  The prompt normally ends with a
  136. colon.
  137.    Sometimes a "default argument" appears in parentheses after the
  138. colon; it too is part of the prompt.  The default will be used as the
  139. argument value if you enter an empty argument (e.g., just type RET).
  140. For example, commands that read buffer names always show a default,
  141. which is the name of the buffer that will be used if you type just RET.
  142.    The simplest way to enter a minibuffer argument is to type the text
  143. you want, terminated by RET which exits the minibuffer.  You can cancel
  144. the command that wants the argument, and get out of the minibuffer, by
  145. typing `C-g'.
  146.    Since the minibuffer uses the screen space of the echo area, it can
  147. conflict with other ways Emacs customarily uses the echo area.  Here is
  148. how Emacs handles such conflicts:
  149.    * If a command gets an error while you are in the minibuffer, this
  150.      does not cancel the minibuffer.  However, the echo area is needed
  151.      for the error message and therefore the minibuffer itself is
  152.      hidden for a while.  It comes back after a few seconds, or as soon
  153.      as you type anything.
  154.    * If in the minibuffer you use a command whose purpose is to print a
  155.      message in the echo area, such as `C-x =', the message is printed
  156.      normally, and the minibuffer is hidden for a while.  It comes back
  157.      after a few seconds, or as soon as you type anything.
  158.    * Echoing of keystrokes does not take place while the minibuffer is
  159.      in use.
  160. * Menu:
  161. * File: Minibuffer File.  Entering file names with the minibuffer.
  162. * Edit: Minibuffer Edit.  How to edit in the minibuffer.
  163. * Completion::          An abbreviation facility for minibuffer input.
  164. * Minibuffer History::    Reusing recent minibuffer arguments.
  165. * Repetition::          Re-executing commands that used the minibuffer.
  166. File: emacs,  Node: Minibuffer File,  Next: Minibuffer Edit,  Up: Minibuffer
  167. Minibuffers for File Names
  168. ==========================
  169.    Sometimes the minibuffer starts out with text in it.  For example,
  170. when you are supposed to give a file name, the minibuffer starts out
  171. containing the "default directory", which ends with a slash.  This is
  172. to inform you which directory the file will be found in if you do not
  173. specify a directory.
  174.    For example, the minibuffer might start out with these contents:
  175.      Find File: /u2/emacs/src/
  176. where `Find File: ' is the prompt.  Typing `buffer.c' specifies the
  177. file `/u2/emacs/src/buffer.c'.  To find files in nearby directories,
  178. use `..'; thus, if you type `../lisp/simple.el', you will get the file
  179. named `/u2/emacs/lisp/simple.el'.  Alternatively, you can kill with
  180. `M-DEL' the directory names you don't want (*note Words::.).
  181.    If you don't want any of the default, you can kill it with `C-a
  182. C-k'.  But you don't need to kill the default; you can simply ignore it.
  183. Insert an absolute file name, one starting with a slash or a tilde,
  184. after the default directory.  For example, to specify the file
  185. `/etc/termcap', just insert that name, giving these minibuffer contents:
  186.      Find File: /u2/emacs/src//etc/termcap
  187. Two slashes in a row are not normally meaningful in a file name, but
  188. they are allowed in GNU Emacs.  They mean, "ignore everything before
  189. the second slash in the pair."  Thus, `/u2/emacs/src/' is ignored in
  190. the example above, and you get the file `/etc/termcap'.
  191.    If you set `insert-default-directory' to `nil', the default
  192. directory is not inserted in the minibuffer.  This way, the minibuffer
  193. starts out empty.  But the name you type, if relative, is still
  194. interpreted with respect to the same default directory.
  195. File: emacs,  Node: Minibuffer Edit,  Next: Completion,  Prev: Minibuffer File,  Up: Minibuffer
  196. Editing in the Minibuffer
  197. =========================
  198.    The minibuffer is an Emacs buffer (albeit a peculiar one), and the
  199. usual Emacs commands are available for editing the text of an argument
  200. you are entering.
  201.    Since RET in the minibuffer is defined to exit the minibuffer, you
  202. can't use it to insert a newline in the minibuffer.  To do that, type
  203. `C-o' or `C-q LFD'.  (Recall that a newline is really the LFD
  204. character.)
  205.    The minibuffer has its own window which always has space on the
  206. screen but acts as if it were not there when the minibuffer is not in
  207. use.  When the minibuffer is in use, its window is just like the
  208. others; you can switch to another window with `C-x o', edit text in
  209. other windows and perhaps even visit more files, before returning to
  210. the minibuffer to submit the argument.  You can kill text in another
  211. window, return to the minibuffer window, and then yank the text to use
  212. it in the argument.  *Note Windows::.
  213.    There are some restrictions on the use of the minibuffer window,
  214. however.  You cannot switch buffers in it--the minibuffer and its
  215. window are permanently attached.  Also, you cannot split or kill the
  216. minibuffer window.  But you can make it taller in the normal fashion
  217. with `C-x ^'.  If you enable Resize-Minibuffer mode, then the
  218. minibuffer window expands vertically as necessary to hold the text that
  219. you put in the minibuffer.  Use `M-x resize-minibuffer-mode' to enable
  220. or disable this minor mode (*note Minor Modes::.).
  221.    If while in the minibuffer you issue a command that displays help
  222. text of any sort in another window, you can use the `C-M-v' command
  223. while in the minibuffer to scroll the help text.  This lasts until you
  224. exit the minibuffer.  This feature is especially useful if a completing
  225. minibuffer gives you a list of possible completions.  *Note Other
  226. Window::.
  227.    Emacs normally disallows most commands that use the minibuffer while
  228. the minibuffer is selected.  This rule is to prevent recursive
  229. minibuffers from confusing novice users.  If you want to be able to use
  230. such commands in the minibuffer, set the variable
  231. `enable-recursive-minibuffers' to a non-`nil' value.
  232. File: emacs,  Node: Completion,  Next: Minibuffer History,  Prev: Minibuffer Edit,  Up: Minibuffer
  233. Completion
  234. ==========
  235.    For certain kinds of arguments, you can use "completion" to enter
  236. the argument value.  Completion means that you type part of the
  237. argument, then Emacs visibly fills in the rest, or as much as can be
  238. determined from the part you have typed.
  239.    When completion is available, certain keys--TAB, RET, and SPC--are
  240. rebound to complete the text present in the minibuffer into a longer
  241. string that it stands for, by matching it against a set of "completion
  242. alternatives" provided by the command reading the argument.  `?' is
  243. defined to display a list of possible completions of what you have
  244. inserted.
  245.    For example, when `M-x' uses the minibuffer to read the name of a
  246. command, it provides a list of all available Emacs command names to
  247. complete against.  The completion keys match the text in the minibuffer
  248. against all the command names, find any additional name characters
  249. implied by the ones already present in the minibuffer, and add those
  250. characters to the ones you have given.  This is what makes it possible
  251. to type `M-x ins SPC b RET' instead of `M-x insert-buffer RET' (for
  252. example).
  253.    Case is normally significant in completion, because it is significant
  254. in most of the names that you can complete (buffer names, file names and
  255. command names).  Thus, `fo' does not complete to `Foo'.  Completion
  256. does ignore case distinctions for certain arguments in which case does
  257. not matter.
  258. * Menu:
  259. * Example: Completion Example.
  260. * Commands: Completion Commands.
  261. * Strict Completion::
  262. * Options: Completion Options.
  263. File: emacs,  Node: Completion Example,  Next: Completion Commands,  Up: Completion
  264. Completion Example
  265. ------------------
  266.    A concrete example may help here.  If you type `M-x au TAB', the TAB
  267. looks for alternatives (in this case, command names) that start with
  268. `au'.  There are only two: `auto-fill-mode' and `auto-save-mode'.
  269. These are the same as far as `auto-', so the `au' in the minibuffer
  270. changes to `auto-'.
  271.    If you type TAB again immediately, there are multiple possibilities
  272. for the very next character--it could be `s' or `f'--so no more
  273. characters are added; instead, TAB displays a list of all possible
  274. completions in another window.
  275.    If you go on to type `f TAB', this TAB sees `auto-f'.  The only
  276. command name starting this way is `auto-fill-mode', so completion fills
  277. in the rest of that.  You now have `auto-fill-mode' in the minibuffer
  278. after typing just `au TAB f TAB'.  Note that TAB has this effect
  279. because in the minibuffer it is bound to the command
  280. `minibuffer-complete' when completion is available.
  281. File: emacs,  Node: Completion Commands,  Next: Strict Completion,  Prev: Completion Example,  Up: Completion
  282. Completion Commands
  283. -------------------
  284.    Here is a list of the completion commands defined in the minibuffer
  285. when completion is available.
  286. `TAB'
  287.      Complete the text in the minibuffer as much as possible
  288.      (`minibuffer-complete').
  289. `SPC'
  290.      Complete the minibuffer text, but don't go beyond one word
  291.      (`minibuffer-complete-word').
  292. `RET'
  293.      Submit the text in the minibuffer as the argument, possibly
  294.      completing first as described below
  295.      (`minibuffer-complete-and-exit').
  296.      Print a list of all possible completions of the text in the
  297.      minibuffer (`minibuffer-list-completions').
  298.    SPC completes much like TAB, but never goes beyond the next hyphen
  299. or space.  If you have `auto-f' in the minibuffer and type SPC, it
  300. finds that the completion is `auto-fill-mode', but it stops completing
  301. after `fill-'.  This gives `auto-fill-'.  Another SPC at this point
  302. completes all the way to `auto-fill-mode'.  SPC in the minibuffer when
  303. completion is available runs the command `minibuffer-complete-word'.
  304.    Here are some commands you can use to choose a completion from a
  305. window that displays a list of completions:
  306. `Mouse-2'
  307.      Clicking mouse button 2 on a completion in the list of possible
  308.      completions chooses that completion (`mouse-choose-completion').
  309.      You use this command while you are in the minibuffer; but you must
  310.      click in the list of completions, not in the minibuffer itself.
  311. `RET'
  312.      Typing RET *in the completion list buffer* chooses the completion
  313.      that point is in or next to (`choose-completion').  To use this
  314.      command, you must first switch windows to the window that shows
  315.      the list of completions.
  316. File: emacs,  Node: Strict Completion,  Next: Completion Options,  Prev: Completion Commands,  Up: Completion
  317. Strict Completion
  318. -----------------
  319.    There are three different ways that RET can work in completing
  320. minibuffers, depending on how the argument will be used.
  321.    * "Strict" completion is used when it is meaningless to give any
  322.      argument except one of the known alternatives.  For example, when
  323.      `C-x k' reads the name of a buffer to kill, it is meaningless to
  324.      give anything but the name of an existing buffer.  In strict
  325.      completion, RET refuses to exit if the text in the minibuffer does
  326.      not complete to an exact match.
  327.    * "Cautious" completion is similar to strict completion, except that
  328.      RET exits only if the text was an exact match already, not needing
  329.      completion.  If the text is not an exact match, RET does not exit,
  330.      but it does complete the text.  If it completes to an exact match,
  331.      a second RET will exit.
  332.      Cautious completion is used for reading file names for files that
  333.      must already exist.
  334.    * "Permissive" completion is used when any string whatever is
  335.      meaningful, and the list of completion alternatives is just a
  336.      guide.  For example, when `C-x C-f' reads the name of a file to
  337.      visit, any file name is allowed, in case you want to create a
  338.      file.  In permissive completion, RET takes the text in the
  339.      minibuffer exactly as given, without completing it.
  340.    The completion commands display a list of all possible completions in
  341. a window whenever there is more than one possibility for the very next
  342. character.  Also, typing `?' explicitly requests such a list.  If the
  343. list of completions is long, you can scroll it with `C-M-v' (*note
  344. Other Window::.).
  345. File: emacs,  Node: Completion Options,  Prev: Strict Completion,  Up: Completion
  346. Completion Options
  347. ------------------
  348.    When completion is done on file names, certain file names are usually
  349. ignored.  The variable `completion-ignored-extensions' contains a list
  350. of strings; a file whose name ends in any of those strings is ignored
  351. as a possible completion.  The standard value of this variable has
  352. several elements including `".o"', `".elc"', `".dvi"' and `"~"'.  The
  353. effect is that, for example, `foo' can complete to `foo.c' even though
  354. `foo.o' exists as well.  However, if *all* the possible completions end
  355. in "ignored" strings, then they are not ignored.  Ignored extensions do
  356. not apply to lists of completions--those always mention all possible
  357. completions.
  358.    Normally, a completion command that finds the next character is
  359. undetermined automatically displays a list of all possible completions.
  360. If the variable `completion-auto-help' is set to `nil', this does not
  361. happen, and you must type `?' to display the possible completions.
  362.    The `complete' library implements a more powerful kind of completion
  363. that can complete multiple words at a time.  For example, it can
  364. complete the command name abbreviation `p-b' into `print-buffer',
  365. because no other command starts with two words whose initials are `p'
  366. and `b'.  To use this library, put `(load "complete")' in your
  367. `~/.emacs' file (*note Init File::.).
  368.    The `icomplete' library does not change what completion does, but it
  369. presents a constantly updated display that tells you what completions
  370. are available.  To use this library, put `(load "icomplete")' in your
  371. `~/.emacs' file.
  372. File: emacs,  Node: Minibuffer History,  Next: Repetition,  Prev: Completion,  Up: Minibuffer
  373. Minibuffer History
  374. ==================
  375.    Every argument that you enter with the minibuffer is saved on a
  376. "minibuffer history list" so that you can use it again later in another
  377. argument.  Special commands load the text of an earlier argument in the
  378. minibuffer.  They discard the old minibuffer contents, so you can think
  379. of them as moving through the history of previous arguments.
  380. `M-p'
  381.      Move to the next earlier argument string saved in the minibuffer
  382.      history (`previous-history-element').
  383. `M-n'
  384.      Move to the next later argument string saved in the minibuffer
  385.      history (`next-history-element').
  386. `M-r REGEXP RET'
  387.      Move to an earlier saved argument in the minibuffer history that
  388.      has a match for REGEXP (`previous-matching-history-element').
  389. `M-s REGEXP RET'
  390.      Move to a later saved argument in the minibuffer history that has a
  391.      match for REGEXP (`next-matching-history-element').
  392.    The simplest way to reuse the saved arguments in the history list is
  393. to move through the history list one element at a time.  While in the
  394. minibuffer, type `M-p' (`previous-history-element') to "move to" the
  395. next earlier minibuffer input, and use `M-n' (`next-history-element')
  396. to "move to" the next later input.
  397.    The previous input that you fetch from the history entirely replaces
  398. the contents of the minibuffer.  To use it as the argument, exit the
  399. minibuffer as usual with RET.  You can also edit the text before you
  400. reuse it; this does not change the history element that you "moved" to,
  401. but your new argument does go at the end of the history list in its own
  402. right.
  403.    There are also commands to search forward or backward through the
  404. history.  As of this writing, they search for history elements that
  405. match a regular expression that you specify with the minibuffer.  `M-r'
  406. (`previous-matching-history-element') searches older elements in the
  407. history, while `M-s' (`next-matching-history-element') searches newer
  408. elements.  By special dispensation, these commands can use the
  409. minibuffer to read their arguments even though you are already in the
  410. minibuffer when you issue them.
  411.    All uses of the minibuffer record your input on a history list, but
  412. there are separate history lists for different kinds of arguments.  For
  413. example, there is a list for file names, used by all the commands that
  414. read file names.  There is a list for arguments of commands like
  415. `query-replace'.  There are several very specific history lists,
  416. including one for command names read by M-x and one for compilation
  417. commands read by `compile'.  Finally, there is one "miscellaneous"
  418. history list that most minibuffer arguments use.
  419. File: emacs,  Node: Repetition,  Prev: Minibuffer History,  Up: Minibuffer
  420. Repeating Minibuffer Commands
  421. =============================
  422.    Every command that uses the minibuffer at least once is recorded on a
  423. special history list, together with the values of its arguments, so that
  424. you can repeat the entire command.  In particular, every use of `M-x'
  425. is recorded there, since `M-x' uses the minibuffer to read the command
  426. name.
  427. `C-x ESC ESC'
  428.      Re-execute a recent minibuffer command (`repeat-complex-command').
  429. `M-x list-command-history'
  430.      Display the entire command history, showing all the commands `C-x
  431.      ESC ESC' can repeat, most recent first.
  432.    `C-x ESC ESC' is used to re-execute a recent minibuffer-using
  433. command.  With no argument, it repeats the last such command.  A
  434. numeric argument specifies which command to repeat; one means the last
  435. one, and larger numbers specify earlier ones.
  436.    `C-x ESC ESC' works by turning the previous command into a Lisp
  437. expression and then entering a minibuffer initialized with the text for
  438. that expression.  If you type just RET, the command is repeated as
  439. before.  You can also change the command by editing the Lisp
  440. expression.  Whatever expression you finally submit is what will be
  441. executed.  The repeated command is added to the front of the command
  442. history unless it is identical to the most recently executed command
  443. already there.
  444.    Even if you don't understand Lisp syntax, it will probably be obvious
  445. which command is displayed for repetition.  If you do not change the
  446. text, it will repeat exactly as before.
  447.    Once inside the minibuffer for `C-x ESC ESC', you can use the
  448. minibuffer history commands (`M-p', `M-n', `M-r', `M-s'; *note
  449. Minibuffer History::.) to move through the history list of saved entire
  450. commands.  After finding the desired previous command, you can edit its
  451. expression as usual and then resubmit it by typing RET as usual.
  452.    The list of previous minibuffer-using commands is stored as a Lisp
  453. list in the variable `command-history'.  Each element is a Lisp
  454. expression which describes one command and its arguments.  Lisp programs
  455. can reexecute a command by calling `eval' with the `command-history'
  456. element.
  457. File: emacs,  Node: M-x,  Next: Help,  Prev: Minibuffer,  Up: Top
  458. Running Commands by Name
  459. ************************
  460.    The Emacs commands that are used often or that must be quick to type
  461. are bound to keys--short sequences of characters--for convenient use.
  462. Other Emacs commands that do not need to be brief are not bound to
  463. keys; to run them, you must refer to them by name.
  464.    A command name is, by convention, made up of one or more words,
  465. separated by hyphens; for example, `auto-fill-mode' or `manual-entry'.
  466. The use of English words makes the command name easier to remember than
  467. a key made up of obscure characters, even though it is more characters
  468. to type.
  469.    The way to run a command by name is to start with `M-x', type the
  470. command name, and finish it with RET.  `M-x' uses the minibuffer to
  471. read the command name.  RET exits the minibuffer and runs the command.
  472. The string `M-x' appears at the beginning of the minibuffer as a
  473. "prompt" to remind you to enter the name of a command to be run.  *Note
  474. Minibuffer::, for full information on the features of the minibuffer.
  475.    You can use completion to enter the command name.  For example, the
  476. command `forward-char' can be invoked by name by typing
  477.      M-x forward-char RET
  478.      M-x forw TAB c RET
  479. Note that `forward-char' is the same command that you invoke with the
  480. key `C-f'.  You can run any Emacs command by name using `M-x', whether
  481. or not any keys are bound to it.
  482.    If you type `C-g' while the command name is being read, you cancel
  483. the `M-x' command and get out of the minibuffer, ending up at top level.
  484.    To pass a numeric argument to the command you are invoking with
  485. `M-x', specify the numeric argument before the `M-x'.  `M-x' passes the
  486. argument along to the command it runs.  The argument value appears in
  487. the prompt while the command name is being read.
  488.    Normally, when describing a command that is run by name, we omit the
  489. RET that is needed to terminate the name.  Thus we might speak of `M-x
  490. auto-fill-mode' rather than `M-x auto-fill-mode RET'.  We mention the
  491. RET only when there is a need to emphasize its presence, such as when
  492. we show the command together with following arguments.
  493.    `M-x' works by running the command `execute-extended-command', which
  494. is responsible for reading the name of another command and invoking it.
  495. File: emacs,  Node: Help,  Next: Mark,  Prev: M-x,  Up: Top
  496.    Emacs provides extensive help features accessible through a single
  497. character, `C-h'.  `C-h' is a prefix key that is used only for
  498. documentation-printing commands.  The characters that you can type after
  499. `C-h' are called "help options".  One help option is `C-h'; that is how
  500. you ask for help about using `C-h'.  To cancel, type `C-g'.
  501.    `C-h C-h' displays a list of the possible help options, each with a
  502. brief description.  Before you type a help option, you can use SPC or
  503. DEL to scroll through the list.
  504.    `C-h' means "help" in various other contexts as well.  For example,
  505. in `query-replace', it describes the options available.  After a prefix
  506. key, it displays a list of the alternatives that can follow the prefix
  507. key.  (A few prefix keys don't support this because they define other
  508. meanings for `C-h'.)
  509. * Menu:
  510. * Help Summary::    Brief list of all Help commands.
  511. * Key Help::        Asking what a key does in Emacs.
  512. * Name Help::        Asking about a command, variable or function name.
  513. * Apropos::        Asking what pertains to a given topic.
  514. * Library Keywords::    Finding Lisp libraries by keywords (topics).
  515. * Misc Help::        Other help commands.
  516. File: emacs,  Node: Help Summary,  Next: Key Help,  Up: Help
  517. Help Summary
  518. ============
  519.    Here is a summary of the defined help commands.
  520. `C-h a REGEXP RET'
  521.      Display list of commands whose names match REGEXP
  522.      (`command-apropos').
  523. `C-h b'
  524.      Display a table of all key bindings in effect now, in this order:
  525.      minor mode bindings, major mode bindings, and global bindings
  526.      (`describe-bindings').
  527. `C-h c KEY'
  528.      Print the name of the command that KEY runs
  529.      (`describe-key-briefly').  Here `c' stands for `character'.  For
  530.      more extensive information on KEY, use `C-h k'.
  531. `C-h f FUNCTION RET'
  532.      Display documentation on the Lisp function named FUNCTION
  533.      (`describe-function').  Since commands are Lisp functions, a
  534.      command name may be used.
  535. `C-h i'
  536.      Run Info, the program for browsing documentation files (`info').
  537.      The complete Emacs manual is available on-line in Info.
  538. `C-h k KEY'
  539.      Display name and documentation of the command that KEY runs
  540.      (`describe-key').
  541. `C-h l'
  542.      Display a description of the last 100 characters you typed
  543.      (`view-lossage').
  544. `C-h m'
  545.      Display documentation of the current major mode (`describe-mode').
  546. `C-h n'
  547.      Display documentation of Emacs changes, most recent first
  548.      (`view-emacs-news').
  549. `C-h p'
  550.      Find packages by topic keyword (`finder-by-keyword').
  551. `C-h s'
  552.      Display current contents of the syntax table, plus an explanation
  553.      of what they mean (`describe-syntax').  *Note Syntax::.
  554. `C-h t'
  555.      Enter the Emacs interactive tutorial (`help-with-tutorial').
  556. `C-h v VAR RET'
  557.      Display the documentation of the Lisp variable VAR
  558.      (`describe-variable').
  559. `C-h w COMMAND RET'
  560.      Print which keys run the command named COMMAND (`where-is').
  561. `C-h C-f FUNCTION RET'
  562.      Enter Info and go to the node documenting the Emacs function
  563.      FUNCTION (`info-goto-emacs-command-node').
  564. `C-h C-k KEY'
  565.      Enter Info and go to the node where the key sequence KEY is
  566.      documented (`info-goto-emacs-key-command-node').
  567. `C-h C-c'
  568.      Display the copying conditions for GNU Emacs.
  569. `C-h C-d'
  570.      Display information about getting new versions of GNU Emacs.
  571. `C-h C-p'
  572.      Display information about the GNU Project.
  573. File: emacs,  Node: Key Help,  Next: Name Help,  Prev: Help Summary,  Up: Help
  574. Documentation for a Key
  575. =======================
  576.    The most basic `C-h' options are `C-h c' (`describe-key-briefly')
  577. and `C-h k' (`describe-key').  `C-h c KEY' prints in the echo area the
  578. name of the command that KEY is bound to.  For example, `C-h c C-f'
  579. prints `forward-char'.  Since command names are chosen to describe what
  580. the commands do, this is a good way to get a very brief description of
  581. what KEY does.
  582.    `C-h k KEY' is similar but gives more information: it displays the
  583. documentation string of the command as well as its name.  This is too
  584. big for the echo area, so a window is used for the display.
  585.    `C-h c' and `C-h k' work for any sort of key sequences, including
  586. function keys and mouse events.
  587. File: emacs,  Node: Name Help,  Next: Apropos,  Prev: Key Help,  Up: Help
  588. Help by Command or Variable Name
  589. ================================
  590.    `C-h f' (`describe-function') reads the name of a Lisp function
  591. using the minibuffer, then displays that function's documentation string
  592. in a window.  Since commands are Lisp functions, you can use this to get
  593. the documentation of a command that you know by name.  For example,
  594.      C-h f auto-fill-mode RET
  595. displays the documentation of `auto-fill-mode'.  This is the only way
  596. to get the documentation of a command that is not bound to any key (one
  597. which you would normally run using `M-x').
  598.    `C-h f' is also useful for Lisp functions that you are planning to
  599. use in a Lisp program.  For example, if you have just written the
  600. expression `(make-vector len)' and want to check that you are using
  601. `make-vector' properly, type `C-h f make-vector RET'.  Because `C-h f'
  602. allows all function names, not just command names, you may find that
  603. some of your favorite abbreviations that work in `M-x' don't work in
  604. `C-h f'.  An abbreviation may be unique among command names yet fail to
  605. be unique when other function names are allowed.
  606.    The function name for `C-h f' to describe has a default which is
  607. used if you type RET leaving the minibuffer empty.  The default is the
  608. function called by the innermost Lisp expression in the buffer around
  609. point, *provided* that is a valid, defined Lisp function name.  For
  610. example, if point is located following the text `(make-vector (car x)',
  611. the innermost list containing point is the one that starts with
  612. `(make-vector', so the default is to describe the function
  613. `make-vector'.
  614.    `C-h f' is often useful just to verify that you have the right
  615. spelling for the function name.  If `C-h f' mentions a default in the
  616. prompt, you have typed the name of a defined Lisp function.  If that is
  617. all you want to know, just type `C-g' to cancel the `C-h f' command,
  618. then go on editing.
  619.    `C-h w COMMAND RET' tells you what keys are bound to COMMAND.  It
  620. prints a list of the keys in the echo area.  If it says the command is
  621. not on any key, you must use `M-x' to run it.  `C-h w' runs the command
  622. `where-is'.
  623.    `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
  624. variables instead of Lisp functions.  Its default is the Lisp symbol
  625. around or before point, but only if that is the name of a known Lisp
  626. variable.  *Note Variables::.
  627. File: emacs,  Node: Apropos,  Next: Library Keywords,  Prev: Name Help,  Up: Help
  628. Apropos
  629. =======
  630.    A more sophisticated sort of question to ask is, "What are the
  631. commands for working with files?"  To ask this question, type `C-h a
  632. file RET', which displays a list of all command names that contain
  633. `file', including `copy-file', `find-file', and so on.  With each
  634. command name appears a brief description of how to use the command, and
  635. what keys you can currently invoke it with.  For example, it would say
  636. that you can invoke `find-file' by typing `C-x C-f'.  The `a' in `C-h
  637. a' stands for `Apropos'; `C-h a' runs the command `command-apropos'.
  638.    Because `C-h a' looks only for functions whose names contain the
  639. string which you specify, you must use ingenuity in choosing the
  640. string.  If you are looking for commands for killing backwards and `C-h
  641. a kill-backwards RET' doesn't reveal any, don't give up.  Try just
  642. `kill', or just `backwards', or just `back'.  Be persistent.  Also note
  643. that you can use a regular expression as the argument, for more
  644. flexibility (*note Regexps::.).
  645.    Here is a set of arguments to give to `C-h a' that covers many
  646. classes of Emacs commands, since there are strong conventions for naming
  647. the standard Emacs commands.  By giving you a feel for the naming
  648. conventions, this set should also serve to aid you in developing a
  649. technique for picking `apropos' strings.
  650.      char, line, word, sentence, paragraph, region, page, sexp, list,
  651.      defun, rect, buffer, frame, window, file, dir, register, mode,
  652.      beginning, end, forward, backward, next, previous, up, down,
  653.      search, goto, kill, delete, mark, insert, yank, fill, indent,
  654.      case, change, set, what, list, find, view, describe.
  655.    To list all Lisp symbols that contain a match for a regexp, not just
  656. the ones that are defined as commands, use the command `M-x apropos'
  657. instead of `C-h a'.  This command does not check key bindings by
  658. default; specify a numeric argument if you want it to check them.
  659.    The `super-apropos' command is like `apropos' except that it
  660. searches documentation strings as well as symbol names for matches for
  661. the specified regular expression.
  662. File: emacs,  Node: Library Keywords,  Next: Misc Help,  Prev: Apropos,  Up: Help
  663. Keyword Search for Lisp Libraries
  664. =================================
  665.    The `C-h p' command lets you search the standard Emacs Lisp
  666. libraries by topic keywords.  Here is a partial list of keywords you can
  667. `abbrev'
  668.      Abbreviation handling, typing shortcuts, macros.
  669. `bib'
  670.      Support for the bibliography processor `bib'.
  671.      C and C++ language support.
  672. `calendar'
  673.      Calendar and time management support.
  674. `comm'
  675.      Communications, networking, remote access to files.
  676. `docs'
  677.      Support for Emacs documentation.
  678. `emulations'
  679.      Emulations of other editors.
  680. `extensions'
  681.      Emacs Lisp language extensions.
  682. `faces'
  683.      Support for using faces (fonts and colors; *note Faces::.).
  684. `games'
  685.      Games, jokes and amusements.
  686. `hardware'
  687.      Support for interfacing with exotic hardware.
  688. `help'
  689.      Support for on-line help systems.
  690. `i18n'
  691.      Internationalization and alternate character-set support.
  692. `internal'
  693.      Code for Emacs internals, build process, defaults.
  694. `languages'
  695.      Specialized modes for editing programming languages.
  696. `lisp'
  697.      Support for using Lisp (including Emacs Lisp).
  698. `local'
  699.      Libraries local to your site.
  700. `maint'
  701.      Maintenance aids for the Emacs development group.
  702. `mail'
  703.      Modes for electronic-mail handling.
  704. `news'
  705.      Support for netnews reading and posting.
  706. `non-text'
  707.      Support for editing files that are not ordinary text.
  708. `processes'
  709.      Process, subshell, compilation, and job control support.
  710. `terminals'
  711.      Support for terminal types.
  712. `tex'
  713.      Support for the TeX formatter.
  714. `tools'
  715.      Programming tools.
  716. `unix'
  717.      Front-ends/assistants for, or emulators of, Unix features.
  718. `vms'
  719.      Support code for VMS.
  720.      Word processing.
  721. File: emacs,  Node: Misc Help,  Prev: Library Keywords,  Up: Help
  722. Other Help Commands
  723. ===================
  724.    `C-h i' (`info') runs the Info program, which is used for browsing
  725. through structured documentation files.  The entire Emacs manual is
  726. available within Info.  Eventually all the documentation of the GNU
  727. system will be available.  Type `h' after entering Info to run a
  728. tutorial on using Info.
  729.    There are two special help commands for accessing Emacs documentation
  730. through Info.  `C-h C-f FUNCTION RET' enters Info and goes straight to
  731. the documentation of the Emacs function FUNCTION.  `C-h C-k KEY' enters
  732. Info and goes straight to the documentation of the key KEY.  These two
  733. keys run the commands `Info-goto-emacs-command-node' and
  734. `Info-goto-emacs-key-command-node'.
  735.    If something surprising happens, and you are not sure what commands
  736. you typed, use `C-h l' (`view-lossage').  `C-h l' prints the last 100
  737. command characters you typed in.  If you see commands that you don't
  738. know, you can use `C-h c' to find out what they do.
  739.    Emacs has numerous major modes, each of which redefines a few keys
  740. and makes a few other changes in how editing works.  `C-h m'
  741. (`describe-mode') prints documentation on the current major mode, which
  742. normally describes all the commands that are changed in this mode.
  743.    `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax')
  744. present other information about the current Emacs mode.  `C-h b'
  745. displays a list of all the key bindings now in effect; the local
  746. bindings defined by the current minor modes first, then the local
  747. bindings defined by the current major mode, and finally the global
  748. bindings (*note Key Bindings::.).  `C-h s' displays the contents of the
  749. syntax table, with explanations of each character's syntax (*note
  750. Syntax::.).
  751.    You can get a similar list for a particular prefix key by typing
  752. `C-h' after the prefix key.  (There are a few prefix keys for which
  753. this does not work--those that provide their own bindings for `C-h'.
  754. One of these is ESC, because `ESC C-h' is actually `C-M-h', which marks
  755. a defun.)
  756.    The other `C-h' options display various files of useful information.
  757. `C-h C-w' displays the full details on the complete absence of
  758. warranty for GNU Emacs.  `C-h n' (`view-emacs-news') displays the file
  759. `emacs/etc/NEWS', which contains documentation on Emacs changes
  760. arranged chronologically.  `C-h t' (`help-with-tutorial') displays the
  761. learn-by-doing Emacs tutorial.  `C-h C-c' (`describe-copying') displays
  762. the file `emacs/etc/COPYING', which tells you the conditions you must
  763. obey in distributing copies of Emacs.  `C-h C-d'
  764. (`describe-distribution') displays the file `emacs/etc/DISTRIB', which
  765. tells you how you can order a copy of the latest version of Emacs.
  766. `C-h C-p' (`describe-project') displays general information about the
  767. GNU Project.
  768. File: emacs,  Node: Mark,  Next: Killing,  Prev: Help,  Up: Top
  769. The Mark and the Region
  770. ***********************
  771.    Many Emacs commands operate on an arbitrary contiguous part of the
  772. current buffer.  To specify the text for such a command to operate on,
  773. you set "the mark" at one end of it, and move point to the other end.
  774. The text between point and the mark is called "the region".  You can
  775. move point or the mark to adjust the boundaries of the region.  It
  776. doesn't matter which one is set first chronologically, or which one
  777. comes earlier in the text.
  778.    Once the mark has been set, it remains where you put it until it is
  779. set again at another place.  The mark remains fixed with respect to the
  780. preceding character if text is inserted or deleted in the buffer.  Each
  781. Emacs buffer has its own mark, so that when you return to a buffer that
  782. had been selected previously, it has the same mark it had before.
  783.    Many commands that insert text, such as `C-y' (`yank') and `M-x
  784. insert-buffer', position point and the mark at opposite ends of the
  785. inserted text, so that the region contains the text just inserted.
  786.    Aside from delimiting the region, the mark is also useful for
  787. remembering a spot that you may want to go back to.  To make this
  788. feature more useful, each buffer remembers 16 previous locations of the
  789. mark in the "mark ring".
  790. * Menu:
  791. * Setting Mark::    Commands to set the mark.
  792. * Transient Mark::    How to make Emacs highlight the region-
  793.               when there is one.
  794. * Using Region::    Summary of ways to operate on contents of the region.
  795. * Marking Objects::    Commands to put region around textual units.
  796. * Mark Ring::       Previous mark positions saved so you can go back there.
  797. * Global Mark Ring::    Previous mark positions in various buffers.
  798. File: emacs,  Node: Setting Mark,  Next: Transient Mark,  Up: Mark
  799. Setting the Mark
  800. ================
  801.    Here are some commands for setting the mark:
  802. `C-SPC'
  803.      Set the mark where point is (`set-mark-command').
  804. `C-@'
  805.      The same.
  806. `C-x C-x'
  807.      Interchange mark and point (`exchange-point-and-mark').
  808. `Drag-Mouse-1'
  809.      Set point and the mark around the text you drag across.
  810. `Mouse-3'
  811.      Set mark where you click (`mouse-save-then-kill').
  812.    For example, suppose you wish to convert part of the buffer to all
  813. upper-case, using the `C-x C-u' (`upcase-region') command which
  814. operates on the text in the region.  You can first go to the beginning
  815. of the text to be capitalized, type `C-SPC' to put the mark there, move
  816. to the end, and then type `C-x C-u'.  Or, you can set the mark at the
  817. end of the text, move to the beginning, and then type `C-x C-u'.
  818.    The most common way to set the mark is with the `C-SPC' command
  819. (`set-mark-command').  This sets the mark where point is.  Then you can
  820. move point away, leaving the mark behind.
  821.    There are two ways to set the mark with the mouse.  You can drag
  822. mouse button one across a range of text; that puts point where you
  823. release the mouse button, and sets the mark at the other end of that
  824. range.  Or you can click mouse button three, which simply sets the
  825. mark, leaving point unchanged.  Both of these methods copy the region
  826. into the kill ring in addition to setting the mark; that gives behavior
  827. consistent with other window-driven applications, but if you don't want
  828. to modify the kill ring, you must use keyboard commands to set the
  829. mark.  *Note Mouse Commands::.
  830.    Ordinary terminals have only one cursor, so there is no way for Emacs
  831. to show you where the mark is located.  You have to remember.  The usual
  832. solution to this problem is to set the mark and then use it soon, before
  833. you forget where it is.  Alternatively, you can see where the mark is
  834. with the command `C-x C-x' (`exchange-point-and-mark') which puts the
  835. mark where point was and point where the mark was.  The extent of the
  836. region is unchanged, but the cursor and point are now at the previous
  837. position of the mark.  In Transient Mark mode, this command reactivates
  838. the mark.
  839.    `C-x C-x' is also useful when you are satisfied with the position of
  840. point but want to move the mark; do `C-x C-x' to put point at that end
  841. of the region, and then move it.  A second use of `C-x C-x', if
  842. necessary, puts the mark at the new position with point back at its
  843. original position.
  844.    There is no such character as `C-SPC' in ASCII; when you type SPC
  845. while holding down CTRL, what you get on most ordinary terminals is the
  846. character `C-@'.  This key is actually bound to `set-mark-command'.
  847. But unless you are unlucky enough to have a terminal where typing
  848. `C-SPC' does not produce `C-@', you might as well think of this
  849. character as `C-SPC'.  Under X, `C-SPC' is actually a distinct
  850. character, but its binding is still `set-mark-command'.
  851. File: emacs,  Node: Transient Mark,  Next: Using Region,  Prev: Setting Mark,  Up: Mark
  852. Transient Mark Mode
  853. ===================
  854.    Many Emacs commands move the mark and invisibly set new regions.
  855. This means that there is almost always some region that you can act on.
  856. This is convenient, provided you get used to keeping track of the
  857. mark's position.
  858.    Some people prefer a more rigid mode of operation in which you must
  859. set up a region for each command that uses one--in which the region
  860. "lasts" only temporarily.  This is called Transient Mark mode.  It is
  861. particularly well-suited to window systems such as X, since Emacs can
  862. highlight the region when it is active.
  863.    To enable Transient Mark mode, type `M-x transient-mark-mode'.  This
  864. command toggles the mode, so you can repeat the command to turn off the
  865. mode.
  866.    Here are the details of Transient Mark mode:
  867.    * To set the mark, type `C-SPC' (`set-mark-command').  This makes
  868.      the mark active; as you move point, you will see the region
  869.      highlighting change in extent.
  870.    * The mouse commands for specifying the mark also make it active.
  871.      So do keyboard commands whose purpose is to specify a region,
  872.      including `M-@', `C-M-@', `M-h', `C-M-h', `C-x C-p', and `C-x h'.
  873.    * When the mark is active, you can execute commands that operate on
  874.      the region, such as killing, indentation, or writing to a file.
  875.    * Any change to the buffer, such as inserting or deleting a
  876.      character, deactivates the mark.  This means any subsequent
  877.      command that operates on a region will get an error and refuse to
  878.      operate.  You can make the region active again by typing `C-x C-x'.
  879.    * Commands like `M->' and `C-s' that "leave the mark behind" in
  880.      addition to some other primary purpose do not activate the new
  881.      mark.  You can activate the new region by executing `C-x C-x'
  882.      (`exchange-point-and-mark').
  883.    * Quitting with `C-g' deactivates the mark.
  884.    * When Transient Mark mode is not enabled, every command that sets
  885.      the mark also activates it, and nothing ever deactivates it.
  886.    Transient Mark mode is also sometimes known as "Zmacs mode" because
  887. the Zmacs editor on the MIT Lisp Machine handled the mark in a similar
  888.    When multiple windows show the same buffer, they can have different
  889. regions, because they can have different values of point (though they
  890. all share common one mark position).  In Transient Mark mode, each
  891. window highlights its own region.  The part that is highlighted in the
  892. selected window is the region that editing commands use.  *Note
  893. Windows::.
  894.